home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Commodore Free 11
/
Commodore_Free_Issue_11_2007_Commodore_Computer_Club.d64
/
t.swl v1
< prev
next >
Wrap
Text File
|
2023-02-26
|
10KB
|
354 lines
u SWL version 1.00
http://www.lyonlabs.org/commodore/
c64.html
Information & help file This file
describes the SWL library for the Power
C compiler (Commodore 64). If you don't
have a copy of the compiler, get it on
my website, http://www.lyonlabs.org
(see the C= 64 section).
Please send bug reports or
documentation errors to me (Glenn
Holmer) The SWL library is a set of
text-based C functions written in
assembler using C-ASSM (also available
on my web site). SWL provides:
-string input with restricted
character and input length
-bordered windows that restore the
screen beneath them when they are
closed
-menus with submenus
-simple widgets (label, text, checkbox,
listbox) that can be grouped It is
distributed as a .D64 image containing
source, object files, a library file,
this documentation, & demo programs.
The basics of using SWL in your
programs are covered here; for detailed
API documentation, see source files:
swl-menu.a swl-menuutil.a swl-wdg.a
swl-wdgutil.a swl-asm.a swl-irq.a
You can see which functions are in each
source file by looking at the .def
statements at the beginning of each
file.To use SWL in your C programs,
include the header swl.h & link with
the library swl.l. The library file &
the 6 object files corresponding to the
source files above must be on your work
disk.
Notes on the SWL API Although SWL was
meant to be called from C, some APIs
have assembler entry points because
they call each other. See the source
code for these entry points & their
calling conventions.
TEXT INPUT The basic building block of
SWL is text input routine, wchrin():
wchrin(string, mask) char *string;
int mask;
Before calling wchrin(), call
swlDinit() to enable the IRQ routine
for the keyboard; you can disable it
again later by calling swlDkill(). The
IRQ service routine has two exported
hooks: ihooktop and ihookbot (see
swl-irq.a).wchrin()'s input can be
restricted by ORing together the
following values in the exported
variable "mask":
$01 (MSKDNUM): numeric input only $02
(MSKDALW): allow only specified
characters $04 (MSKDEND): use input
terminator table ("endkeys") $80
(MSKDCHK): checkbox input: 1 character
only,
space only, toggles a checkmark
MSKDNUM and MSKDALW can be combined
(e.g. numeric with decimal point), but
MSKDCHK trumps both (it is meant for
the checkbox widget described below).
The allowed keys and end keys are in
16-byte character arrays named
"allowed" and "endkeys". To add or
remove end keys for an individual
call to wchrin, call addEnder &
rmvEnder (in swl-irq.a). For allowed
keys, just strcpy the characters to the
allowed array (there is an API for this
if you are using widgets).
WINDOWS SWL supports text-based
windows, which are written directly to
screen memory. The area of the screen
occupied by the window is buffered &
restored when the window is closed. Up
to 8 windows at a time can be open, &
they can overlap.
openWnd(left, top, width, height,
title) int left, top, width, height;
clsWnd( )
There is also a routine to draw a box
on the screen, which is not buffered:
drawBox(left, top, width, height) int
left, top, width, height;
CURSOR LOCATION There are 2 routines to
set the cursor location:
locate(x, y) int x, y;
wlocate(x, y) int x, y;
locate() sets the x and y cursor
position (counting from 0) & clears the
screen line link table. wlocate()
checks to see if a window is open: if
so, it locates the cursor within the
window, otherwise it calls locate().
wlocate() returns FALSE
(0) if the coordinates are out of range
for the window. MENUS SWL has support
for menus, which can appear anywhere on
the screen. Menus are represented by a
menu structure with a pointer to a
singly-linked list of menu item
structures. A submenu is a menu item
with a pointer to the submenu. There
are "constructor" functions for menus &
menu items, as well as functions to add
items & submenus to a menu:
struct *menu newMenu(left, top, parent,
title) int left, top; struct menu
*parent; char *title;
struct *menuitem newItem(text) char
*text;
addItem(menu, item) struct menu *menu;
struct item *item;
struct *menuitem addmenu(menu
submenu) struct menu *menu, *submenu;
See the header file for the structure
definition (note that there are fields
called mExtend & iExtend that can be
used to "subclass" these structures).
There are 2 types of menu:
struct *menu doMenu(menuptr) struct
menu *menuptr;
struct *menu doList(menuptr) struct
menu *menuptr;
doMenu() draws the menu within a
window and restores the screen after-
ward; doList() draws the menu using
drawBox() and does not restore the
screen. In addition, doList() ignores
submenus. It is meant for simple
listboxes (see the listbox widget
described below). Menus are exited with
Enter (ENTER) or F5 (KEYDEXIT), & end
keys are respected, meaning you can
check the value of endkey to see how a
menu was exited (you can also check the
menu's mEndkey field). The return value
is the menu structure the user exited
from (which may be a submenu), or 0 if
a top-level menu was dismissed with F5.
If a menu item was chosen with Enter,
the menu structure's mChosen field will
be set to TRUE
(1) and the mCuritem field will
indicate which item was selected (you
will have to walk the item structures
with a counter to get to it; see
menutest.c for an example). Menu items
can contain a pointer to a dispatch
function (iAction), so you can just
check to see if that's non-null & call
it if so. WIDGETS
The widget APIs pull together all the
elements of SWL to allow the creation
of input screens or dialogs where the
user can use the keyboard to move back
& forth among several fields & accept
or cancel the input as a whole. The
keys, inspired by Q-Link, are F7/F8 to
move forward & backward among the
widgets, F1 to accept, & F5 to cancel.
They are defined in swl.h.
A group of widgets is a circular,
doubly-linked list of widget
structures. There are four types of
widgets: labels, text input, checkbox,
& listbox (all of which share the same
structure). All widgets are displayed
when doWidget() is first called. During
the data entry loop, label widgets are
ignored, but text inputs are handled by
wchrin(). Checkbox widgets are also
handled by wchrin(), but with the
special flag
MSKDCHK, which allows only a single
space as input and uses it to toggle
between a check mark & an underscore.
Listbox widgets call the doList() form
of menu. As with menus, there are
"constructor" functions as well as a
function to add them to a group:
struct *widget newLbl(left, top,
text) int left, top; char *text;
struct *widget newTxt(left, top,
text) int left, top; char *text;
struct *widget newChk(left, top,
state, dummy) int left, top, state;
char *dummy;
struct *widget newList(left, top,
menu) int left, top; struct menu
*menu;
addWdg(widget, firstWdg) struct
widget *widget, *firstWdg) ;
Each widget has its own set of end keys
& allowed keys. End keys are added to
the endkeys table when each widget
gains focus, & removed afterward (since
the function keys must remain active),
but each widget's allowed keys replace
the allowed keys table while it has
focus. As with menus, the widget
structure has a field named wExtend for
"subclassing" (in fact, the listbox
widget uses it to store the menu
pointer). To display a group of
widgets, call initWdg() to set up the
function keys (make sure to call
swlDinit() as well if you are using
text or checkbox widgets) , then call
doWidget() with a pointer to the first
widget of the group:
doWidget(first, inWindow) struct
widget *first; int inWindow;
The inWindow argument indicates whether
the widgets are contained within a
window; if so, the window cursor
location routine is used, & any widgets
that would extend beyond the right edge
of the window are truncated before
display. When doWidget() returns, call
killWdg( ) to remove the function keys
from the endkeys table, & swlDkill() if
you were using text or checkbox
widgets.
The return value is a pointer to the
widget the user exited from (or 0 if
any screen locations are invalid) As
with menus, widgets can have dispatch
functions. With widgets, however, the
loop will exit as soon as a widget with
a dispatch routine loses focus. The
reason for this is so that one widget
can affect another (e.g. a checkbox
changing another widget from text input
to a label to disable it)
To make this happen, SWL would have to
call the C dispatch function from
within the widget loop's assembler
code, which I was not prepared to do
(it would also have required an add-
itional flag to indicate that the
dispatch should be called immediately).
The solution is to check manually for a
dispatch function when the loop exits,
& handle this on a case-by-case basis
(re-entering the loop after the
dispatch has been called if you want to
continue)
There is an example of this technique
in the demo program wdgtest.c.
UTILITY ROUTINES SWL also provides some
utility routines:
int banner(text, edge, align) char
*text; int edge, align;
Draws a banner at the top or bottom
edge of the screen in reverse video,
aligned left, center, or right. See
swl.h for constants (BNRD for edge &
ALND for alignment)
char wgetchar() ;
Reads a character from the keyboard
(blocks until a key is pressed)
char wgetkey() ;
Reads a character from the keyboard
(non-blocking, may return 0)
ASSEMBLER UTILITY ROUTINES If you are
using assembler, there are some add-
itional routines available that are not
callable from C. These are documented
in swlasm.a & swl-irq.a: multiply
(integer multiply) beep (sound a bell)
savtemp (save temporary variable area)
rsttemp (restore temporary variable
area)
charout (write a character to screen)
scnout (write a screen code to screen)
KNOWN BUGS There are no known bugs at
this time. Please send bug reports to
the address at the top of this file.
KNOWN LIMITATIONS There is no support
for screen colors or custom character
sets. The APIs for adding end keys &
allowed keys are not consistent